Getting Started

NZ Post Group is committed to continuously improving and expanding the services it provides its customers. Where possible, NZ Post will make changes to the API but not change the version number because the changes are considered to be "non-breaking" for you, the consumer.

Non-breaking changes can include:

• API implementation changes that do not change the API interface

API interfaces changes that we consider non-breaking:

• Addition of new resources
• Addition of new non-mandatory request parameters of attributes
• Addition of new data fields returned in the response
• Change in the order of data fields returned by the API

API application developers should develop their code so that these types of changes will not break their application

From time to time new versions of existing API’s will be created to include enhancements or new features relating to our parcel services. Changes that are consider a breaking change and require a version change are:

• Renaming of resources, parameters, attributes
• Inclusion or removal of mandatory parameters
• Restructuring of the API interface

As upgrades of the API’s are made available to our integrators, the version number will be incremented. Upon release of a new version, your applications can continue to use the current version while you assess the need to upgrade. Release notes will be provided with every release describing the change and its impacts in detail. Upon upgrading, integrators are encouraged to execute their own regression tests in the UAT environment against the new version prior to upgrading to the new API version in production.

Customers are asked to maintain a version within 2 major releases of the latest version or higher to ensure that the highest quality of service is provided to you and to your own customers. Older versions of the API’s will be deprecated, meaning that they will be available for use by existing customers but they will not be available to new customers. From time to time, a legacy version of an API will be decommissioned. Users of the legacy version will be contacted directly regarding an upgrade time frame.